Integration Guide for Product Providers
OneBasket has been designed to integrate with product and service providers that have varying levels of functionalities and technical competency.
No two providers are the same, and OneBasket equips integrators with the tools they need to integrate systems of varying technical competence into their stores.
Some providers, for example, might provide a full suite APIs that correspond to the full feature set of a typical OneBasket integration. Others may not have APIs and provide CSV files of data, and a more bespoke integration is in order.
The spectrum between these two extremes is vast.
This guide serves as a checklist to assess a given vendors functional capabilities in respect to building an integration into OneBasket, but does not replace a formal architectural process.
Key Integration Points
When architecting an integration into OneBasket with a new provider system, there are a number of key areas which need to be investigated to determine the type of integration that can be created. The results of this investigation will help you determine the types of data synchronisation and communication mechanisms employed to create a complete integration with the provider.
Below are the common areas that need to be considered up front. You can use this as a guide, but generally speaking, any new integration will always be designed by architects both from the OneBasket side and, if available, the product providers side also.
The bare minimum set of features have been marked as "Mandatory", however it should be noted that the specific approach to achieve the mandatory requirements are not always as simple as calling an API endpoint, which again is why a formal architectural process is necessary between from Stadion and a technical representative from the provider.
Catalogues
The Catalogues service in OneBasket is responsible for enabling the products from all disparate providers to be findable behind a single product API.
The common functionalities to look for when integrating a new provider system into the catalogues system of OneBasket includes:
| Necessity | Feature | Details |
|---|---|---|
| Mandatory | Product catalogue | Products and services can be synchronised into OneBasket via an API or other mechanism. |
| Mandatory | Pricing and availabilty | Product pricing and availability can be synchronised into OneBasket via an API or other mechanism. Depending on the provider, this may come in the main product catalogue synchronisation, for others could be split between multiple API calls to different endpoints. |
| Optional | Organisational structures | Products taxonomy (categories, tags and catalogues) can be synchronised into OneBasket via an API or other mechanism. This can include the existince of one or more catalogue structures. This might be as complex as the sales windows for tickets for a match built on top of a customer loyalty program, or as simple as a "start" and "end" date range that a product can be available for sale within. |
| Optional | Purchase eligibility | Ability for the provider to inform OneBasket what products certain customers are eligible to purchase, and other aspects of purchase eligibility, such as when they can be purchased, and for how long. |
Baskets
The Baskets service in OneBasket is responsible for allowing customers to add products from any disparate provider into a single basket, assign delivery methods, capture guest customer details, etc and ultimately make payment with a single transaction.
The common functionalities to look for when integrating a new provider system into the baskets system of OneBasket includes:
| Necessity | Feature | Details |
|---|---|---|
| Mandatory | Delivery methods | Ability for the provider to inform OneBasket what are the availabile delivery methods for the products in the basket. |
| Optional | Maintain basket state | The provider system manages the basket state in their service, maintaining the provider system as the source of truth for basket time inventory rules, pricing and other aspects of the basket's state. Whilst optional, it adds further integration work in order to backfill these features (where possible) to ensure the costumer recieves a solid user experience (for example, not thinking they have purchased something only to find out later there is no stock left). See the "Orders" section for aspects of the checkout process. |
| Optional | Inventory locking | Sometimes called "reservations". Usually relevant to time sensitive products, such as tickets. Ability for OneBasket to lock product inventory in order to ensure that payment processing can be completed without the inventory being freed after basket expiration. |
Orders
The Orders service in OneBasket is responsible for issuing orders into third party systems, and coordinating the confirmation and fulfilment of those orders.
The common functionalities to look for when integrating a new provider system into the orders system of OneBasket includes:
It's worth noting that sometimes a given provider system can use the same concept to handle both the baskets and orders facets described below.
For example, a provider system might not have the concept of "basket" but only the concept of "order". When creating a "basket" in OneBasket, in the provider system we might actually be creating a "draft order". When payment is taken, we then might convert that order into a completed state. This is an example of how a provider integration maps concepts between systems.
In simpler situations, provider systems have the concept of both a "basket" and an "order", mapping 1:1 to OneBasket concepts.
OneBasket has been designed to be flexible in this regard, which is why we are able to integrate with any provider.
| Necessity | Feature | Details |
|---|---|---|
| Mandatory | Payment authority | OneBasket allows customers to purchase everything in their basket in a single transaction. This requires provider systems to act as a payment method on their end, so that when a basket has been paid for and an order is being submitted to the provider, that order is accepted and confirmed to be fulfilled. |
| Mandatory | Order creation | OneBasket needs to be able to notify the provider that a basket has been paid for, and an order on its end needs to be fulfilled. |
| Optional | Fulfilment events | The ability for the provider to send order fulfilment updates back to OneBasket. For example, in F&B this can be used to allow OneBasket to notify the customer when their order is ready to pick up at a collection point. |
Contacts
The Contacts service in OneBasket is responsible for identifying customers for the purposes of personalising their ecommerce experience (such as eligibilties to purchase limited supply products), and capture data about their ecomm activities for the purposes of building a richer customer profile.
You can think of the term "contact" as "customer record" or simply "user" in this regard.
| Necessity | Feature | Details |
|---|---|---|
| Mandatory (in some cases) | Contact linking | When dealing with an SSO system, it is sometimes necessary that OneBasket is able to associate a purchase with the given customer, even if the provider system has not completed a full integration with the SSO system. This entails OneBasket being able to either:
|
| Optional | Contact synchronisation | In some cases it can be necessary to synchronise contact details from the provider system, such as cases where we are showing pre saved postal delivery addresses. |
| Optional | Purchase eligibility | Related to the above in the catalogues section, sometimes these purchase eligibilities come through as attributes on the customer's contact record itself. |
| Optional | Contact updates | In some cases, the provider needs to provide OneBasket with updates when a contact record changes, for example if their product eligibility changes. |
| Optional | Contact management | Depending on the business rules of OneBasket store, as well as the rules of the provider system itself, OneBasket needs to be able to create and update contact records in the provider system as part of purchasing workflow. This includes also checking for the existence of existing contacts based on information passed as part of guest checkout flow. |
Cross Cutting
The following cross cutting concerns need to be taken into account when integrating with a new product provider.
| Necessity | Feature | Details |
|---|---|---|
| Optional | Multi-currency | Depending on the regional structure of the provider, it may be required that the provider system is able to provide product pricing in a local currency. |
| Optional | Multi-locale | Depending on the regional structure of the provider, it may be required that the provider system is able to provide titles, descriptions, labels and other customer facing content in multiple languages. |
In Summary
OneBasket has been designed to accomodate a wide range of provider systems, from those with full APIs to those with no APIs at all. The key to a successful integration is to understand the capabilities of the provider system, and to design an integration that is both technically feasible and provides a good user experience for the customer.
Stadion engineers are here to assist from an architectural perspective, as well as provide development guidance when the integration is not being built by our team.